Frontmatter 拓展

什么是 Frontmatter

Frontmatter 是 YAML 格式的 Markdown 文件头，如：

markdown

---
title: Frontmatter 拓展
date: 2025-09-13 18:35:12
permalink: /guide/frontmatter
---

## 什么是 Frontmatter

--- 之间的语法，就是 Frontmatter。通过 Frontmatter 可以给 Markdown 文件添加元数据，如：标题、作者、日期、链接等等。

如果只是单纯查看 Markdown 文件，Frontmatter 的作用仅仅是添加标识，并没实际作用，但是在某些主题、框架、工具库中，Frontmatter 的作用就变得很重要了，部分的主题、框架、工具库会根据 Frontmatter 的内容，进行一些特殊处理或开启特殊功能，如 Teek 的 title 配置代表给该文件添加一个一级标题，在启动 Teek 后，文章页的一级标题会变成 title 的值。

Frontmatter 拓展

Teek 提供了丰富的 Frontmatter 配置，如常用的 title、date、permalink、categories 等，具体参阅 Frontmatter 配置。

部分 Frontmatter 配置可以极大的改善网站的访问体验，但是每次新增一个 Markdown 文件，都要手动添加 Frontmatter 配置，非常麻烦。

因此 Teek 提供了自动生成 Frontmatter 的功能，当新建了一个 Markdown 文件，并启动项目时，Teek 会给所有没有 Frontmatter 的 Markdown 文件自动添加一些 Teek 内置的 Frontmatter 配置。

Frontmatter 自动生成功能，会直接修改 Markdown 文档的 frontmatter，因此为了安全性考虑，默认是关闭的，如果希望开启，进行如下配置：

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
  },
});

如果开启了该功能，那么 Teek 将会对所有 Markdown 文档的 frontmatter 添加如下格式：

yaml

---
title: getting
date: 2025-03-03 00:45:16
permalink: /pages/eb8f2f
categories:
  - guide
---

title 为文章的标题
date 为文章的创建时间
permalink 为文章的永久链接，采用随机数确保唯一
categories 为文章的分类，根据目录层级获取

提示

Teek 不会修改已经存在的数据，判断的规则是比较 key，不比较 value。

开启自动生成 Frontmatter 的功能后，可以通过 autoFrontmatterOption 来进行部分配置。

取消 categories 自动生成

如果您不希望自动生成 categories，则将进行如下配置：

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
    autoFrontmatterOption: {
      categories: false,
    },
  },
});

permalink 配置

这是本文主要的介绍内容。

permalink 配置，可以自定义文章的永久链接。关于 permalink 的具体介绍，请参阅永久链接，接下来的内容是介绍 permalink 的自动生成功能。

关闭 permalink 自动生成

如果您不希望自动生成 permalink，则将进行如下配置：

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
    autoFrontmatterOption: {
      permalink: false,
    },
  },
});

permalink 生成规则 v1.5.0

Teek 生成 permalink 的规则有两个：

simple 规则：该规则的生成格式是 /pages/{随机六位数}，当你第一次开启 Frontmatter 自动生成功能时，就会看到该规则生成的 permalink
rules 规则：该规则需要您完全自定义 permalink 的生成格式，相较于 simple 规则，该规则的生成格式更灵活，但是需要您自己进行配置

为了兼容 rewrites 模式，Teek 根据 vitePlugins.sidebarOption.resolveRule 的内容来进行动态判断，你可以在永久链接来了解 resolveRule 配置是做什么的。

当 vitePlugins.sidebarOption.resolveRule 为 filePath 则 permalink 生成规则默认为 simple
当 vitePlugins.sidebarOption.resolveRule 为 rewrites 则 permalink 生成规则默认为 rules

默认情况下，vitePlugins.sidebarOption.resolveRule 为 filePath，因此您可以认为 permalink 默认生成规则是 simple。

除了动态判断决定默认值之外，您可以强制指定 permalink 的生成规则，这样不会受到 resolveRule 配置的影响：

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
    autoFrontmatterOption: {
      permalinkType: "rules", // 可选：simple | rules
    },
  },
});

simple 规则

(1)默认情况下、(2)手动式设置 permalinkType 为 simple、(3)permalinkType 为 simple 时，这任意 3 个方式会开启 simple 规则。

simple 规则的 permalink 生成格式是 /pages/{随机六位数}。

如果您不希望以 /pages 开头，则自定义一个前缀：

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
    autoFrontmatterOption: {
      permalinkPrefix: "pages", // 默认为 pages，可以修改为自定义值
    },
  },
});

rules 规则

当手动式设置 permalinkType 为 rules 或 vitePlugins.sidebarOption.resolveRule 为 rewrites 时，会开启 rule 规则。

rule 规则允许您自定义 permalink 的生成格式，格式如下：

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
    autoFrontmatterOption: {
      permalinkType: "rules",
      permalinkRules: [
        { folderName: "01.guide", rule: "/$path/$uuid6" }, // 使用一级目录的哈希混合随机数，$path 最终等于 guide
        { folderName: "10.配置/01.主题配置", rule: "/reference/$uuid6" }, // 使用混合固定字符串和随机数
        { folderName: "15.主题开发", rule: "/willRemove/develop/$uuid6", removeLevel: 1 }, // 先移除一层前缀，再添加前缀，等价于 /develop/$uuid6
        { folderName: "20.资源", rule: "/test-$uuid4-$uuid2/aaa/" }, // 使用混合固定字符串和随机数
        { folderName: "30.生态", rule: "/$path-$uuid2/teek/$uuid" }, // 使用一级目录的哈希混合随机数
        // { folderName: "*" }, // '*' 代表所有文件都生成永久链接，不设置 rule 则默认为 /$path/$uuid6
      ],
    },
  },
});

permalinkRules 是一个数组，数组的每一项都是一个对象，对象包含 3 个属性：

folderName

类型：string
默认值：undefined

一级目录名称，一级目录名称必须与 Markdown 文件所在一级目录名称一致，如果为 * 则代表所有一级目录。

rule

类型：string
默认值：/$path/$uuid6

指定 permalink 生成格式，除了固定的字符串还支持 2 个变量：

$path{num}

生成一个 6-10 长度的哈希值，根据 Markdown 文件所在一级目录名进行哈希处理得到的哈希值，{num} 则可以指定哈希值的长度，不指定 {num} 时默认为 6，如文件路径为 /01.指南/01.简介.md，则 $path 为 01.指南 的哈希值。

如果 Markdown 文件所在一级目录名为英文，则 $path 为不会进行哈希处理，直接以目录名作为 $path 的值（支持「序号.」开头）。

$uuid{num}

生成一个 1-15 长度的随机字符串，{num} 则可以指定随机字符串的长度，不指定 {num} 时默认为 6。

removeLevel

类型：number
默认值：0

要移除的前缀层级（以 / 分割），如 permalink 为 /test/xx 时，removeLevel 为 1，则最终生成的 permalink 为 /xx，当 removeLevel 为 99，则会移除所有层级，只剩根路径。

生成文章列表封面图 v1.5.0

在 post.defaultCoverImg 配置项提供封面图链接数组，Teek 在页面加载时会给每一个文章列表随机选择一个封面图，但是这是隐形且有随机性，您无法直观的查看某一个文章列表的封面图链接，因此可以用 Frontmatter 自动生成封面图链接功能。

自动生成封面图链接本质上就是在 Frontmatter 中添加 coverImg 属性，而 coverImg 属性值需要您提供一个封面图链接数组。

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
    autoFrontmatterOption: {
      coverImg: true, // 开启自动生成封面图链接功能
      coverImgList: ["https://a", "https://b"], // 封面图链接数组
    },
  },
});

这样 Teek 会给每一个文章随机从 coverImgList 取出一个链接，在 Frontmatter 中添加 coverImg 键值。

默认情况下，如果 Markdown 文件的 Frontmatter 已经存在 coverImg 属性，则不会重新生成，但是当更新了 coverImgList 后，希望 coverImg 的属性值重新生成，那么有 2 种方式达到目的：

先删除 coverImg 属性，再重新运行项目生成，如果认为每个 Markdown 文件删除 coverImg 属性麻烦，则可以参阅下面的删除部分属性内容进行一次性全部删除
设置 forceCoverImg 配置项为 true 来开启强制重新生成 coverImg 的属性值。

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
    autoFrontmatterOption: {
      coverImg: true, // 开启自动生成封面图链接功能
      forceCoverImg: true, // 强制重新生成 coverImg 的属性值
      coverImgList: ["https://a", "https://b"], // 封面图链接数组
    },
  },
});

警告

一旦重新生成后，请将 forceCoverImg 配置项设置为 false 或者去掉，否则每次启动项目都会重新生成 coverImg 的属性值。

删除部分属性

如果您想删除部分 Frontmatter 的属性，可以使用 transform 函数来实现，如清空 permalink 配置：

import { defineTeekConfig } from "vitepress-theme-teek/config";

const teekConfig = defineTeekConfig({
  vitePlugins: {
    autoFrontmatter: true,
    autoFrontmatterOption: {
      transform: frontmatter => {
        // 清空 permalink 属性
        delete frontmatter.permalink;
        return frontmatter;
      },
    },
  },
});

如果想清空其他属性，请自行修改 transform 函数的 delete frontmatter.{配置} 内容。

警告

一旦删除指定的属性后，则需要去掉 transform 的删除逻辑，否则每次启动项目都会尝试删除该属性，可能会对后续使用该属性造成影响。

Frontmatter 拓展 ​

什么是 Frontmatter ​

Frontmatter 拓展 ​

取消 categories 自动生成 ​

permalink 配置 ​

关闭 permalink 自动生成 ​

permalink 生成规则 v1.5.0 ​

simple 规则 ​

rules 规则 ​

生成文章列表封面图 v1.5.0 ​

删除部分属性 ​

Frontmatter 拓展

什么是 Frontmatter

Frontmatter 拓展

取消 categories 自动生成

permalink 配置

关闭 permalink 自动生成

permalink 生成规则 v1.5.0

simple 规则

rules 规则

生成文章列表封面图 v1.5.0

删除部分属性